Note: #111 has been split out of this PR to allow for an independent review of the changes. I am unable to point the base branch to the branch of that PR, as this causes the PR to be created in the forked repo. I hope that #111 can be reviewed and merged first, and then this PR is rebased on top of the changes; however, I have opened this PR to show the utility of some of the hooks added in that PR, e.g. mypy or some of the more opinionated ruff rules.

Summary

This PR introduces a new hook to run the ruff formatted over code blocks in documentation files. This was built on top of the Blacken-docs project but extended for the ruff formatter. I think this hook should be included in this repo rather than Blacken-docs, as it allows the hook to be versioned with the correct version of ruff and automatically updated when a new version of ruff is added rather than relying on manual updates of the ruff version (as is currently implemented with black in blacken-docs).

Naming

Initially, I had thought of this hook as ruffen-docs; however, I believe ruff-format-docs aligns better with the other hooks in this repo and also leaves open the door for a ruff-check-docs hook in the future.

Licencing

The Blacken-docs repo is licenced under an MIT Licence, so I believe that using it as a starting point is covered by this. I have also included a reference to the Blacken-docs repo in the readme.

Test Plan

• Test cases ported from blacken-docs
• Try with try-repo in another repo that has code blocks in documentation e.g. the main ruff repo. uv run pre-commit try-repo <path-to-pre-commit-ruff> ruff-format-docs --files crates/**/resources/mdtest/*.md
  • Main changes introduced here are the addition of extra white blank lines before function definitions
  • Note some files fail to parse, but these are due to invalid syntax in the files. These files are excluded by the current blacken-docs config in this repo.